Handle mkdocs/GitHub admonition conversions #466
Conversation
GitHub doesn't natively render mkdocs admonitions, making the markdown docs hard to read in the repo. This script allows us to maintain a "GitHub-first" source while deploying a "Mkdocs-working" site by introducing the convert_docs script.
|
This looks awesome to me! Would love @zeroasterisk to take a look seeing as he understand the mkdocs deployment pipleine. |
|
Hmmm... pretty cool solution. I'm good with it. I may add a README to the /docs/scripts/ folder explaining what the supported conversions are.... but no reason to block this PR to make that happen. Thanks @nan-yu for the contribution! ❤️ |
|
Actually one more thing before I merge.... This is currently bi-directional. Shouldn't it instead be uni-directional? From github markdown to mkdocs markdown? We don't need the return trip for any reason, unless we are going to add CI/CD linting to throw errors on PR review and enforce github markdown format. @nan-yu I'm going to merge, but if you're feeling generous and want to make a 2nd pass, I'd rather have a smaller uni-directional transform potentially with PR linting enforcement vs bi-directional transformer. |
Thanks for the merge! The bi-directional support was initially there to covert the I'll follow up with a PR to simplify the transformer. |
done in #564, which also adds a README file in the scripts directory. |
3 participants
GitHub doesn't natively render mkdocs admonitions, making the markdown docs hard to read in the repo.
The pure GitHub markdown loses styling consistency provided by mkdocs admonitions.
This PR adds a script that allows us to maintain a "GitHub-first" source while deploying a "Mkdocs-working" site by introducing the convert_docs script.